---
title: Migrating from Legacy to Native Filters
sidebar_position: 5
version: 1
---

##

The `superset native-filters` CLI command group—somewhat akin to an Alembic migration—
comprises of a number of sub-commands which allows administrators to upgrade/downgrade
existing dashboards which use the legacy filter-box charts—in combination with the
filter scopes/filter mapping—to use the native filter dashboard component.

Even though both legacy and native filters can coexist the overall user experience (UX)
is substandard as the already convoluted filter space becomes overly complex. After
enabling the `DASHBOARD_NATIVE_FILTERS` it is strongly advised to run the migration ASAP to
ensure users are not exposed to the hybrid state.

### Upgrading

The

```
superset native-filters upgrade
```

command—which provides the option to target either specific dashboard(s) or all
dashboards—migrates the legacy filters to native filters.

Specifically, the command performs the following:

- Replaces every filter-box chart within the dashboard with a markdown element which
provides a link to the deprecated chart. This preserves the layout whilst simultaneously
providing context to help owners review/verify said change.
- Migrates the filter scopes/filter mappings to the native filter configuration.

#### Quality Control

Dashboard owners should:

- Verify that the filter behavior is correct.
- Consolidate any conflicting/redundant filters—this previously may not have been
obvious given the embedded nature of the legacy filters and/or the non-optimal UX of the
legacy filter mapping (scopes and immunity).
- Rename the filters—which may not be uniquely named—to provide the necessary context
which previously was likely provided by both the location of the filter-box and the
corresponding filter-box title.

Dashboard owners may:

- Remove† the markdown elements from their dashboards and adjust the layout accordingly.

† Note removing the markdown elements—which contain metadata relating to the replaced
chart—prevents the dashboard from being fully restored and thus this operation should
only be performed if it is evident that a downgrade is not necessary.

### Downgrading

Similarly the

```
superset native-filters downgrade
```

command reverses said migration, i.e., restores the dashboard to the previous state.


### Cleanup

The ability to downgrade/reverse the migration requires temporary storage of the
dashboard metadata—relating to both positional composition and filter configuration.

Once the upgrade has been verified it is recommended to run the

```
superset native-filters cleanup
```

command—which provides the option to target either specific dashboard(s) or all
dashboards. Note this operation is irreversible.

Specifically, the command performs the following:

- Removes the temporary dashboard metadata.
- Deletes the filter-box charts associated with the dashboard†.

† Note the markdown elements will still remain however the link to the referenced filter-box
chart will no longer be valid.

#### Quality Control

Dashboard owners should:

- Remove the markdown elements from their dashboards and adjust the layout accordingly.
